/**
 *
 */
package mwt.xml.xdbforms.xformlayer.transactions;

import java.io.InputStream;
import java.io.OutputStream;
import mwt.xml.xdbforms.xformlayer.transactions.exception.XFormTransactionException;
import mwt.xml.xdbforms.xformlayer.transactions.impl.Submission;

/**
 * Classe XFormTransaction: definisce un'interfaccia comune per eseguire
 * un operazione di inserimento o aggiornamento di una riga della tabella
 * specificata.
 * @author Gianfranco Murador, Cristian Castiglia, Matteo Ferri
 * Copyright (C) 2009, MCG08
 */
public interface XFormTransaction {
    
    
    /**
     *
     * Richiede il documento xform per l'esecuzione di una transazione,
     * in questo caso il documento avrà gli elementi del modello dati
     * riempiti con i valori precedenti se le chiavi hanno dato un risultato
     * non nullo (caso update).
     * @param table Nome della tabella
     * @param keys  lista di valori da inserire come filtro per le chiavi primarie 
     * @throws mwt.xml.xdbforms.xformlayer.transactions.exception.XFormTransactionException
     * <b>Nota:</b> il database corrente deve essere specificato tramite la 
     * ConnectionFactory
     */

    public void require(String table,Submission s,Object[] keys) throws XFormTransactionException;

    /**
     * Richiede il documento xform per l'esecuzione di una transazione 
     * @param table Nome della tabella
     * @throws mwt.xml.xdbforms.xformlayer.transactions.exception.XFormTransactionException
     * <b>Nota:</b> il database corrente deve essere specificato tramite la
     * ConnectionFactory
     */
    public void require(String table,Submission s) throws XFormTransactionException;

    /**
     * Esegue il commit del documento xml passato tramite il submit di una richiesta
     * <b>Nota:</b> vedere la specifica di xform per ulteriori dettagli
     * @param writer
     * @throws mwt.xml.xdbforms.xformlayer.transactions.exception.XFormTransactionException
     */

    public void commit(InputStream inputStream) throws XFormTransactionException;

    /**
     * Ritorna il documento xform dell'ultima richiesta fatta.
     * Se l'ultima require definisce delle chiavi allora il metodo
     * restituisce un documento xform con il modello dei dati riempiti
     * con i valori. (Caso update).
     * @return xform document
     * @throws mwt.xml.xdbforms.xformlayer.transactions.exception.XFormTransactionException
     */

    public String getDocument(OutputStream os) throws XFormTransactionException;

    /**
     * Ritorna lo schema del documento xform dell'utlima richiesta fatta
     * scrivendolo nell'OutputStream passato in input
     * @return xschema document
     * @throws mwt.xml.xdbforms.xformlayer.transactions.exception.XFormTransactionException
     */

    public String getSchemasBinding(OutputStream os) throws XFormTransactionException;


    /***
     * Ritorna l'istanza dei dati scrivendola nello OutputStream in input
     * @param os
     * @throws mwt.xml.xdbforms.xformlayer.transactions.exception.XFormTransactionException
     */

    public String getDataInstance(OutputStream os) throws XFormTransactionException;

    /**
     * Ritorna l'instanza dei valori ammissibili scrivendola nell'OutputStream
     * passato in input
     * @param os
     * @throws mwt.xml.xdbforms.xformlayer.transactions.exception.XFormTransactionException
     */


    public String getValuesInstance(OutputStream os) throws XFormTransactionException;


    /**
     * Fa il merge di tutti i modelli dati all'interno di un singolo documento
     * @param os
     * @throws mwt.xml.xdbforms.xformlayer.transactions.exception.XFormTransactionException
     */
    public String getMergedDocument() throws XFormTransactionException;



}
